feat: AI 톤 교정 API (#65 3/3) - #87

관련 이슈

• closes [feat] AI 톤 교정 API #65 (3/3, API·문서)

작업 내용

① #85 → ② 서비스 #86 위에 쌓았습니다. ②가 병합되면 기준 브랜치를 develop으로 바꿉니다.

• 커밋: ccb627e, 272935a, 96201ac, 8501137
• 서버 내부 오류(500)도 선점한 1회를 반환 (feat: AI 톤 교정 서비스 (#65 2/3) #86 리뷰 반영, 8501137): 선점 뒤 실패는 correct()의 catch 한 곳에서만 반환해 이중 반환 없음. 명세 22번 비고·버전 표 갱신
• POST /api/v1/ai/tone-corrections (AiToneCorrectionController, @LoginUser Long userId)
• 성공 코드 AiSuccessCode.TONE_CORRECTED (AI200_1, 200, "톤 교정에 성공했습니다.")
• 요청 AiToneCorrectRequest(style, text): 필드 순서 style → text (검증 에러는 첫 번째 하나만). style은 문자열로 받아 @ValidToneStyle로 검사
• 응답 AiToneCorrectResponse: correctedText, style, keyInfoWarning, usage
  • keyInfoWarning: 차이가 없으면 null, 있으면 명세 문구 + missingValues·addedValues
  • usage.resetAt은 전역 직렬화 설정으로 +09:00
• 요청·응답의 toString은 원문·결과 대신 길이와 개수만 보임 (스프링 디버그 로그가 요청 본문 객체를 toString으로 찍음)
• 문서
  • CLAUDE.md: 출력 토큰 상한 4000 → 6000
  • docs/s1-api-spec.md 22번 비고: 출력 토큰 상한 4,000 → 6,000, 처리 중 이탈 문구 변경. 버전 표에 한 줄 추가

명세와 달라진 점

이 PR에서 명세를 함께 고침

• 22번 비고 출력 토큰 상한 4,000 → 6,000: [feat] AI 톤 교정 문체 열거형 · 문체별 지시문 #64 실제 모델 확인에서 3000자 원문 보고/공문 교정이 4,000에서 5회 중 2회 잘림. 6,000에서는 20회 모두 정상 종료(최대 4662토큰·16.1초)
• 22번 비고 처리 중 이탈: "서버가 연결 끊김을 감지하면 되돌리지만…" → "지금은 서버가 연결 끊김을 감지하지 않아, 처리 중 화면을 떠나도 횟수가 차감됩니다." 동기 서블릿에서는 외부 호출을 기다리는 동안 연결 끊김을 알 수 없음. 비동기 처리로 바꾸는 후속 이슈에서 다시 다룸 (프론트 공유 필요)

테스트

통합 테스트 (실제 필터·MySQL, 언어 모델은 가짜 구현을 감싼 스파이로 실패를 만듦, 트랜잭션 없이 실행)

• 성공: 200 AI200_1, 명세 순서의 필드, 선점 후 사용량(1회 → 남은 4), 23:59:30 요청의 resetAt이 2026-10-12T00:00:00+09:00, Cache-Control: no-store
• 날짜가 빠지거나 바뀌면 정상 응답에 명세 문구의 keyInfoWarning, 횟수는 차감된 채
• 5회 사용 후 6번째는 AI429_1, 언어 모델을 부르지 않음
• 거절·표식 AI422_1, 외부 오류 AI502_1, 시간 초과 AI504_1, 각각 사용량이 요청 전 값으로 돌아감
• style 빈 값·ESSAY·소문자·없는 값 → AI400_1 (COMMON400_1 아님), 둘 다 없으면 AI400_1, text 없음·공백만 → AI400_2, 3000자 통과·3001자 AI400_3. 검증 실패는 사용량 행이 생기지 않음
• 없는 회원 번호의 토큰 → USER404_1, 사용량 행 없음 (500 아님)
• 토큰 없이 요청 → 401 COMMON401_1
• 성공·422·502·504·예상 못 한 500에서 출력 캡처에 원문·결과 문자열이 없고, 결과 종류·소요 시간·출력 토큰 수는 남음
• 에러 응답 모두 no-store, result는 null

원문·결과는 저장하는 테이블·컬럼이 없음 (코드 확인)

결정하지 않고 둔 것 (#65 "결정 필요")

• 표식이 문장 안에 섞인 응답: 지금 판정(앞뒤 공백을 지운 응답이 표식과 정확히 같을 때만 차단) 그대로라, 섞이면 결과로 나감. [feat] AI 톤 교정 문체 열거형 · 문체별 지시문 #64 확인에서 표식 응답 105건 중 섞임 0건
• 결과의 마크다운 **: 서버에서 지우지 않음. [feat] AI 톤 교정 문체 열거형 · 문체별 지시문 #64 최종 확인에서 3000자 보고/공문 5회 중 1회

확인 체크리스트

• ./gradlew build 통과
• 테스트 포함
• 변경 400줄 안팎 (+435 −3, 그중 통합 테스트 283줄)
• 병합된 마이그레이션 수정 안 함
• 비밀 값·개인정보 없음
• global 공통 코드를 바꿨다면 디스코드에 공유함 (변경 없음)

리뷰어에게

[중점] 처리 중 이탈 명세 변경(프론트 공유 필요), 응답 필드와 keyInfoWarning null 처리